﻿// ===============================================================================
// IConfiguration.cs
// EOS Framework
// ===============================================================================
// Copyright (c) EOS Development Group. All rights reserved.
// ===============================================================================

namespace EOS.Framework.Contracts.Configuration
{
    using System.Collections.Generic;
    using System.Diagnostics.CodeAnalysis;

    /// <summary>
    /// Contract for all configuration modules.
    /// </summary>
    public interface IConfiguration
    {
        /// <summary>
        /// True, if already loaded, else false.
        /// </summary>
        bool Loaded { get; }

        /// <summary>
        /// Loads the configuration with the specified file name.
        /// </summary>
        /// <param name="fileName">Name of the file. Cannot be null or empty.</param>
        /// <exception cref="ArgumentNullException"><paramref name="fileName"/> is
        /// null (Nothing in Visual Basic).</exception>
        /// <exception cref="ArgumentException"><paramref name="fileName"/> is a string
        /// with length 0 or contains only blanks.</exception>
        /// <exception cref="InvalidOperationException">Configuration file is already loaded.</exception>
        /// <exception cref="FileNotFoundException">Configuration file does not exist.</exception>
        void Load(string fileName);

        /// <summary>
        /// Adds a value to the config file at the specified path.
        /// </summary>
        /// <typeparam name="T">Type of the value to add.</typeparam>
        /// <param name="path">The path, where the value should be stored.</param>
        /// <param name="value">The value to store.</param>
        /// <exception cref="ArgumentNullException">
        /// 	<para><paramref name="path"/> is null (Nothing in Visual Basic).</para>
        /// 	<para>- or -</para>
        /// 	<para><paramref name="value"/> is null (Nothing in Visual Basic).</para>
        /// </exception>
        /// <exception cref="ArgumentException">
        ///     <para><paramref name="fileName"/> is a string with length 0 or contains only blanks.</para>
        ///     <para>- or -</para>
        ///     <para><paramref name="value"/> is a collection.</para>
        /// </exception>
        void AddValue<T>(string path, T value);

        /// <summary>
        /// Sets the value at the specified path.
        /// </summary>
        /// <typeparam name="T">Type of the value to add.</typeparam>
        /// <param name="path">The path, where the value should be stored.</param>
        /// <param name="value">The value to store.</param>
        /// <exception cref="ArgumentNullException">
        /// 	<para><paramref name="path"/> is null (Nothing in Visual Basic).</para>
        /// 	<para>- or -</para>
        /// 	<para><paramref name="value"/> is null (Nothing in Visual Basic).</para>
        /// </exception>
        /// <exception cref="ArgumentException">
        ///     <para><paramref name="fileName"/> is a string with length 0 or contains only blanks.</para>
        ///     <para>- or -</para>
        ///     <para><paramref name="value"/> is a collection.</para>
        /// </exception>
        void SetValue<T>(string path, T value);

        /// <summary>
        /// Sets the value list at the specified apth.
        /// </summary>
        /// <typeparam name="T">Type of an list item.</typeparam>
        /// <param name="path">The path, where the list should be stored..</param>
        /// <param name="list">The list to add.</param>
        /// <exception cref="ArgumentNullException">
        /// 	<para><paramref name="path"/> is null (Nothing in Visual Basic).</para>
        /// 	<para>- or -</para>
        /// 	<para><paramref name="list"/> is null (Nothing in Visual Basic).</para>
        /// </exception>
        /// <exception cref="ArgumentException"><paramref name="fileName"/> is a string
        /// with length 0 or contains only blanks.</exception>
        [SuppressMessage("Microsoft.Design", "CA1002")]
        void SetValueList<T>(string path, List<T> list);

        /// <summary>
        /// Gets the value at the specified path.
        /// </summary>
        /// <typeparam name="T">Type of the value.</typeparam>
        /// <param name="path">The path.</param>
        /// <returns>The value at the path.</returns>
        /// <exception cref="ArgumentNullException"><paramref name="fileName"/> is
        /// null (Nothing in Visual Basic).</exception>
        /// <exception cref="ArgumentException"><paramref name="fileName"/> is a string
        /// with length 0 or contains only blanks.</exception>
        [SuppressMessage("Microsoft.Design", "CA1004")]
        T GetValue<T>(string path);

        /// <summary>
        /// Gets the value list at the specified path.
        /// </summary>
        /// <typeparam name="T">Type of a list item.</typeparam>
        /// <param name="path">The path.</param>
        /// <returns>The value list at the path</returns>        
        /// <exception cref="ArgumentNullException"><paramref name="fileName"/> is
        /// null (Nothing in Visual Basic).</exception>
        /// <exception cref="ArgumentException"><paramref name="fileName"/> is a string
        /// with length 0 or contains only blanks.</exception>
        [SuppressMessage("Microsoft.Design", "CA1002")]
        [SuppressMessage("Microsoft.Design", "CA1004")]
        List<T> GetValueList<T>(string path);
    }
}
